Summary

This change enables usage-based charges settled through customer credits to use a custom credit currency while the customer invoice remains denominated in fiat.

Usage is realized in the custom currency and available customer credits are allocated in that same currency. Any usage not covered by credits becomes overage and is converted to the invoice currency using the cost basis selected for the charge.

The overage must be invoiced as a credit purchase. The invoice line represents the uncovered custom-currency amount purchased at the charge's persisted cost basis, with the resulting fiat amount becoming the customer's outstanding balance.

Business behavior

• usage and credit allocation remain denominated in the charge's custom currency
• the persisted cost basis determines the fiat value of uncovered usage
• the invoice contains one credit-purchase line for the overage
• the credit-purchase quantity is the uncovered custom-currency amount
• the credit-purchase unit price is the persisted cost basis
• invoice collection and payment use the resulting fiat amount
• final and progressive realization follow the same settlement behavior, including late-arriving usage

This keeps customer credit accounting in the credit currency while ensuring invoices, outstanding balances, and payments remain fiat-denominated.

Validation

• make test-nocache — 6,379 tests passed, 15 skipped
• focused usage-based charge and subscription-sync lifecycle suites

Summary by CodeRabbit

• New Features
  • Added conversion of custom-currency overages into fiat amounts using cost basis.
  • Introduced custom-currency overage handling for credit-then-invoice, including lifecycle persistence and fiat overage placeholder/overage annotations.
• Bug Fixes
  • Payment authorization and settlement now properly skip or reject flows when the fiat amount is zero.
  • Invoice collection timing now considers explicit overage collection deadlines.
• Documentation
  • Updated testing guidance for fixed UTC timestamps.
• Tests
  • Expanded unit and lifecycle coverage for custom-currency conversion, validations, collection timing, and zero-value payment behavior.

Greptile Summary

Adds custom-currency usage settlement through fiat invoices.

• Converts uncovered custom-currency usage to fiat using the persisted cost basis.
• Represents overage as a credit-purchase invoice line and propagates fiat amounts through collection and payment.
• Adds lifecycle, conversion, collection-timing, and zero-value payment coverage.

Confidence Score: 5/5

The PR appears safe to merge within this follow-up review because no new blocking failure eligible for a distinct comment remains.

No blocking failure eligible for this follow-up review remains.

Important Files Changed

sequenceDiagram
    participant Usage as Usage Rating
    participant Credits as Credit Allocation
    participant Charge as Usage Charge
    participant Invoice as Fiat Invoice
    participant Ledger as Ledger
    Usage->>Charge: Realize usage in custom currency
    Charge->>Credits: Allocate matching customer credits
    Credits-->>Charge: Return uncovered custom-currency amount
    Charge->>Charge: Convert overage using persisted cost basis
    Charge->>Invoice: Create fiat credit-purchase line
    Invoice->>Ledger: Accrue and settle fiat balance

_{Reviews (3): Last reviewed commit: "fix(customcurrencies): preserve overage ..." | Re-trigger Greptile}